folderitem.htmlHTMLudogà0πùΔ£πùΔ£ÅÅu% Monkeybread Realbasic plugin - Documentation - Folderitem

MBS Plugin Documentation

This is the documentation for the Realbasic Plugins from Monkeybreadsoftware.de. You find these plugins and the newest version of this document at http://www.monkeybreadsoftware.de/realbasic inside the plugins section.

This help was last updated on Freitag, 6. September 2002 and covers 2136 items: 126 classes, 2 controls and 583 global functions.

The list of the themes Global methods by category Global methods by name The list of the classes The list of the controls

addLoginItem(appfile as folderitem, hide as boolean, allusers as boolean)
global method, Login Items Sa, 27. Jul 2002
Mac OS Classic: Does nothing Mac OS Carbon: Works Windows: Does nothing
Function: Adds a file to the loginitems list.
Example:
dim f as folderItem

f=app.applicationFile
if addLoginItem(f,false,false) then
msgBox f.displayName+" has been added to the login items!"
else
msgBox "Something went wrong."
end if
Notes:
hide matches the checkbox in the loginitems list.
allusers decides whether to set it for all user or the current one.

class Folderitem
class, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works party.

AFPUserName as string
method, AFP So, 14. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> "".
Function: Returns the user name of the volume the folderitem points to.
Notes:
Usefull to see which name someone used to mount the volume.
Apple didn't implemented this function for Mac OS X 10.1.4. Maybe for a later one?

AsAlias(rel as folderitem) as string
method, Alias Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Creates a binary string with data to restore this folderitem.
Example:
dim f,r as folderitem
dim s as string
...
r=getfolderitem("") // relative to application path
s=f.AsAlias(r)
Notes:
Creates a string with an Alias Record on Mac and on Windows a path.
This string is not an aliasrecord itself, but a structure where 9 additional bytes are used to verify length and content. So you can later Resolve a Windows path on Mac which will just return nil.

ColorCode as integer
method, Finder Label Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> 0.
Function: Returns the color code for the file.
Example: f.colorcode=2
Notes:
The Color code is a number between 0 and 7 to give the file a color.
Used in the Classic Finder for labels.
On reading the value you can get negative values like -43 if the file is not found.

ColorSyncCountImageProfiles as integer
method, ColorSync Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> 0.
Function: Use this function to obtain a count of the number of embeded profiles for a given image.
Notes:
Returns 0 if the function fails for any reason.
Requires ColorSync 2.6 or newer.

ColorSyncEmbedImage(target as folderitem,replace as boolean,Profile as ColorSyncProfile) as boolean
method, ColorSync Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> false.
Function: This function will embed an image with an ICC profile.
Notes:
If target is a file, it specifies the resulting image. If this parameter is a folder, it specifies the location of the resulting image which will have the same name as the original file. If this parameter is nil, the original file is modified.
If a file with the same name already exists, it will be replaced if this parameter replace is set to true.
Returns false if the function fails for any reason.
Requires ColorSync 2.6 or newer.

ColorSyncGetImageProfile(index as integer) as ColorSyncProfile
method, ColorSync Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> nil.
Function: Use this function to obtain a specific embeded profile for a given image.
Notes:
Returns nil if the function fails for any reason.
Requires ColorSync 2.6 or newer.

ColorSyncImageColorSpace as string
method, ColorSync Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> "".
Function: What color space does this picture use?
Example: msgbox file.ColorSyncImageColorSpace
Notes:
Possible values:

"XYZ "The XYZ data color space.
"Lab "The L*a*b* data color space.
"Luv "The L*u*v* data color space.
"Yxy "The Yxy data color space.
"RGB "The RGB data color space.
"sRGB"The RGB data color space.
"GRAY"The Gray data color space.
"HSV "The HSV data color space.
"HLS "The HLS data color space.
"CMYK"The CMYK data color space.
"CMY "The CMY data color space.
"MCH5"The five-channel multichannel (HiFi) data color space.
"MCH6"The six-channel multichannel (HiFi) data color space.
"MCH7"The seven-channel multichannel (HiFi) data color space.
"MCH8"The eight-channel multichannel (HiFi) data color space.

Other values whitout a defition from Apple:

"3CLR", "4CLR", "5CLR", "6CLR", "7CLR", "8CLR", "NAME", "9CLR", "ACLR", "BCLR", "CCLR", "DCLR", "ECLR", "FCLR".

Requires ColorSync 2.6 or newer.

ColorSyncLinkImage(target as folderitem,replace as boolean,quality as integer,linkprofile as ColorSyncProfile,linkintent as integer) as boolean
method, ColorSync Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> false.
Function: Use this function to match an image file with a device link profile.
Notes:
If target is a file, it specifies the resulting image. If this parameter is a folder, it specifies the location of the resulting image which will have the same name as the original file. If this parameter is nil, the original file is modified.
If a file with the same name already exists, it will be replaced if this parameter replace is set to true.
Returns false if the function fails for any reason.

Quality values:
cmNormalMode0This is the default setting. Normal mode indicates that the CMM should use its default method to compromise between performance and resource requirements.
cmDraftMode1Draft mode indicates that the CMM should sacrifice quality, if necessary, to minimize resource requirements. Note that the default CMM currently produces the same results for both normal and draft mode.
cmBestMode2Best mode indicates that the CMM should maximize resource usage to ensure the highest possible quality.

Intent values:
cmPerceptual0All the colors of a given gamut can be scaled to fit within another gamut. This intent is best suited to realistic images, such as photographic images.
cmRelativeColorimetric1The colors that fall within the gamuts of both devices are left unchanged. This intent is best suited to logo images.
cmSaturation2The relative saturation of colors is maintained from gamut to gamut. This intent is best suited to bar graphs and pie charts in which the actual color displayed is less important than its vividness.
cmAbsoluteColorimetric3This approach is based on a device-independent color space in which the result is an idealized print viewed on a ideal type of paper having a large dynamic range and color gamut.

Requires ColorSync 2.6 or newer.

ColorSyncMatchImage(target as folderitem,replace as boolean,quality as integer,sourceprofile as ColorSyncProfile,sourceintent as integer,destprofile as ColorSyncProfile) as boolean
method, ColorSync Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> 0.
Function: Use this function to color match an image file.
Notes:
If target is a file, it specifies the resulting image. If this parameter is a folder, it specifies the location of the resulting image which will have the same name as the original file. If this parameter is nil, the original file is modified.
If a file with the same name already exists, it will be replaced if this parameter replace is set to true.
Returns false if the function fails for any reason.

Quality values:
cmNormalMode0This is the default setting. Normal mode indicates that the CMM should use its default method to compromise between performance and resource requirements.
cmDraftMode1Draft mode indicates that the CMM should sacrifice quality, if necessary, to minimize resource requirements. Note that the default CMM currently produces the same results for both normal and draft mode.
cmBestMode2Best mode indicates that the CMM should maximize resource usage to ensure the highest possible quality.

Intent values:
cmPerceptual0All the colors of a given gamut can be scaled to fit within another gamut. This intent is best suited to realistic images, such as photographic images.
cmRelativeColorimetric1The colors that fall within the gamuts of both devices are left unchanged. This intent is best suited to logo images.
cmSaturation2The relative saturation of colors is maintained from gamut to gamut. This intent is best suited to bar graphs and pie charts in which the actual color displayed is less important than its vividness.
cmAbsoluteColorimetric3This approach is based on a device-independent color space in which the result is an idealized print viewed on a ideal type of paper having a large dynamic range and color gamut.

Requires ColorSync 2.6 or newer.

ColorSyncProofImage(target as folderitem,replace as boolean,quality as integer,sourceprofile as ColorSyncProfile,sourceintent as integer,destprofile as ColorSyncProfile,proofprofile as ColorSyncProfile) as boolean
method, ColorSync Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> false.
Function: Use this function to proof an image file.
Notes:
If target is a file, it specifies the resulting image. If this parameter is a folder, it specifies the location of the resulting image which will have the same name as the original file. If this parameter is nil, the original file is modified.
If a file with the same name already exists, it will be replaced if this parameter replace is set to true.
Returns false if the function fails for any reason.

Quality values:
cmNormalMode0This is the default setting. Normal mode indicates that the CMM should use its default method to compromise between performance and resource requirements.
cmDraftMode1Draft mode indicates that the CMM should sacrifice quality, if necessary, to minimize resource requirements. Note that the default CMM currently produces the same results for both normal and draft mode.
cmBestMode2Best mode indicates that the CMM should maximize resource usage to ensure the highest possible quality.

Intent values:
cmPerceptual0All the colors of a given gamut can be scaled to fit within another gamut. This intent is best suited to realistic images, such as photographic images.
cmRelativeColorimetric1The colors that fall within the gamuts of both devices are left unchanged. This intent is best suited to logo images.
cmSaturation2The relative saturation of colors is maintained from gamut to gamut. This intent is best suited to bar graphs and pie charts in which the actual color displayed is less important than its vividness.
cmAbsoluteColorimetric3This approach is based on a device-independent color space in which the result is an idealized print viewed on a ideal type of paper having a large dynamic range and color gamut.

Requires ColorSync 2.6 or newer.

ColorSyncSetImageProfile(target as folderitem,replace as boolean,index as integer,profile as ColorSyncProfile) as boolean
method, ColorSync Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> false.
Function: Use this function to set a specific embeded profile for a given image.
Notes:
If target is a file, it specifies the resulting image. If this parameter is a folder, it specifies the location of the resulting image which will have the same name as the original file. If this parameter is nil, the original file is modified.
If a file with the same name already exists, it will be replaced if this parameter replace is set to true.
Returns false if the function fails for any reason.
Requires ColorSync 2.6 or newer.

ColorSyncUnembedImage(target as folderitem,replace as boolean) as boolean
method, ColorSync Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> false.
Function: This function will remove any ICC profiles embeded in an image.
Notes:
If target is a file, it specifies the resulting image. If this parameter is a folder, it specifies the location of the resulting image which will have the same name as the original file. If this parameter is nil, the original file is modified.
If a file with the same name already exists, it will be replaced if this parameter replace is set to true.
Returns false if the function fails for any reason.
Requires ColorSync 2.6 or newer.

ColorSyncValidImage as integer
method, ColorSync Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> 0.
Function: Is this a valid image for ColorSync?
Notes:
Return values:
0Windows
1No ColorSync 2.6 or newer
2Not valid
3Valid

You can look in the folder ColorSyncScriptingFolder which picture formates are supported. In Mac OS X 10.1.5 there are TIFF, JPEG and GIF.

(The ColorSyncScriptingFolder function is part of the MBS Plugin)

Requires ColorSync 2.6 or newer.

Comment as string
method, Folderitem So, 5. Mai 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> "".
Function: Returns the comment for that file.
Example: f.comment="Hello world!"
Notes:
The comment is limited in Mac OS 9 to 200 chars. But it should be 255 chars on Mac OS X.
The actual length depends on the file system.

CreateLargeBinaryStream(forkName as String, mactype as string,maccreator as string) as LargeBinaryStream
method, Large binary stream Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Creates a file as a LargeBinaryStream.
Example: l=f.CreateLargeBinaryStream(SystemDataForkName,"TEXT","ttxt")
Notes:
Use SystemDataForkName or SystemResourceForkName for the fork names.
On Windows the three parameters are ignored.

CreateResStream(mactype as string,maccreator as string) as ResStream
method, Ressourcefork Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> nil.
Function: Creates a new ResStream.
Notes:
If there is allready a file, it's deleted.
If the file could not be created it's deleted.

CreatorApp() as FolderItem
method, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: returns allways nil
Function: Returns the application that would be launched if you'd call the above Launch method, or NIL if no appropriate app can be located.
Example: appfile=docfile.CreatorApp

CreatorApp(creatorCode as String) as FolderItem
method, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: returns allways nil
Function: Returns a folderitem to the Application which created this file for the given creator code on the volume of the folderitem.
Example:
appfile=myvolume.CreatorApp("iCAB")
' or
ok = theFile.OpenWithApp(GetCreatorApp("RSED"), inFront)
Notes:
Returns the application that would be launched if you'd call the above Launch method and if the file had the specified creator code. Returns NIL if no appropriate app can be located.

This method allows you to open a document with a creator code that you specify instead of having to locate the application by your own. Here's an example on how to open any file with ResEdit (whose creator code is 'RSED'):

DeleteDataFork
method, Ressourcefork Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Does nothing.
Function: Deletes the data fork of a file.
Notes: Equal to open the file using a binarystream and setting the length property to 0.

DeleteResourceFork
method, Ressourcefork Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Does nothing.
Function: Deletes the resource fork of a file.
Notes: Equal to open the file using a resstream and setting the length property to 0.

DrawIcon(g as Graphics,x as integer,y as integer)
method, Icon Service Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Draws the icon of the folderitem on the position x/y inside the graphics object.
Example: systemfolder.drawicon canvas1.graphics,0,0
Notes:
The works with masks.
For every other size than 32 pixels use DrawWideIcon.

DrawWideIcon(g as Graphics,x as integer,y as integer,width as integer)
method, Icon Service Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Draws the icon of the folderitem on the position x/y inside the graphics object with the given width.
Example: app.applicationfile.DrawWideIcon canvas1.graphics,0,0,128 'for the nice OSX icons
Notes:
The works with masks.
Works even wonderfull with OSX Icons.

equal(item as folderitem) as boolean
method, Folderitem Sa, 27. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Compiled, but untested.
Function: Checks whether two folderitems point to the same location.
Example:
if f.equals(g) then
'same file or folder
end if
Notes:
On Windows it's comparing using pathes and on Mac using internal numbers.
Not tested for network volumes.

FBCIndexItem as boolean
method, FindbyContent Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Seems not to work correctly. Windows: -> false.
Function: Indexes the given folderitem.
Notes:
The folderitem can be a file, a folder or a volume.
Find by Content seems not to work correctly on Mac OS X.

FBCVolumeIndexPhysicalSize as integer
method, FindbyContent Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Seems not to work correctly. Windows: -> 0.
Function: Returns the size of the volume's index file in bytes.
Notes:
Find by Content seems not to work correctly on Mac OS X.
This function seems to return on Mac OS X 10.1.5 allways 100000.

FBCVolumeIndexTimeStamp as double
method, FindbyContent Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Seems not to work correctly. Windows: -> 0.
Function: Returns the time when the volume's index was last updated.
Notes:
Find by Content seems not to work correctly on Mac OS X.
This function seems to return on Mac OS X 10.1.5 allways 572662306.

FBCVolumeIsIndexed as boolean
method, FindbyContent Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Seems not to work correctly. Windows: -> false.
Function: Is this volume indexed?
Notes:
Find by Content seems not to work correctly on Mac OS X.
This function seems to return on Mac OS X 10.1.5 allways true.

FBCVolumeIsRemote as boolean
method, FindbyContent Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Seems not to work correctly. Windows: -> false.
Function: Is this volume remote?
Notes:
Find by Content seems not to work correctly on Mac OS X.
This function seems to return on Mac OS X 10.1.5 allways false.

FontActivateGlobal as integer
method, Fonts Sa, 3. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> -1.
Function: Activates one or more fonts.
Notes:
The folderitem used here points to a directory or an individual font file.
If you want the Font Manager to make the fonts visible only to your application use FontActivateLocal.
If you want the Font Manager to make fonts visible to all applications installed on the system, use the FontActivateGlobal.

Requires Mac OS 9.0 or newer.
Returns -1 if this FontManager function was not found.

FontDeactivate as integer
method, Fonts Sa, 3. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> -1.
Function: Deactivates one or more fonts.
Notes:
The folderitem used here points to a directory or an individual font file.

Requires Mac OS 9.0 or newer.
Returns -1 if this FontManager function was not found.

FontDeactivate as integer
method, Fonts Sa, 3. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> -1.
Function: Activates one or more fonts.
Notes:
The folderitem used here points to a directory or an individual font file.
If you want the Font Manager to make the fonts visible only to your application use FontActivateLocal.
If you want the Font Manager to make fonts visible to all applications installed on the system, use the FontActivateGlobal.

Requires Mac OS 9.0 or newer.
Returns -1 if this FontManager function was not found.

FSRef as memoryblock
method, Folderitem So, 21. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> nil.
Function: Returns the FSRef to this folderitem as a memoryblock.
Notes:
Only usefull for toolbox calls.
Requires Mac OS X or Mac OS 9.
If the folderitem's file doesn't exist, you get the parent folder's FSRef.

FSSpec as memoryblock
method, Folderitem So, 21. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> nil.
Function: Returns the FSSpec to this folderitem as a memoryblock.
Example:
dim f,g as folderItem
dim m as memoryBlock

f=getfolderItem("")

m=f.FSSpec

g=NewFolderItemFSSpec(m)
msgBox g.absolutePath // same path as f
Notes: Only usefull for toolbox calls.

GetFileAttribute as Integer
method, Folderitem So, 26. Mai 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Get the file attributes for the folderitem to the given value. Returns a negative if there is an error.
Notes:
Returns the flAttrib of a file. If you pass in a non-existing file or a folder, a negative error code is returned instead.
The flAttrib is a set of bits with the following meaning:
bit 0,value 1file is locked
bit 2,value 4resource fork is open
bit 3,value 8data fork is open
bit 4,value 16item is a directory
bit 7,value 128file (one or both forks) is open
(See GetFileFlags for an example on how to check the bits)

GetFileFlags as Integer
method, Folderitem So, 26. Mai 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Get the file flags for a folderitem.
Example:
For example, testing for a file being invible works like this:
fdFlags = f.GetFileFlags
if fdFlags < 0 then
... oops, an error occured
else
fileIsInvisible = BitwiseAnd (fdFlags, &H4000) <> 0
end
Notes:
Returns the fdFlags of a file. If you pass in a non-existing file or a folder, a negative error code is returned instead.

The fdFlags is a set of bits with the following meaning:
bit 15value &H8000isAlias
bit 14value &H4000isInvisible
bit 13value &H2000hasBundle (has a BNDL resource)
bit 12value &H1000nameLocked
bit 11value &H0800isStationary
bit 10value &H0400hasCustomIcon
bit 8value &H0100hasBeenInited (Finder has seen the file since it has been created)
bit 7value &H0080hasNoINITs (there's no INIT rsrc in the Extension file)
bit 6value &H0040isShared
bits 1-3value &H000Ecolor (as a 3-bit value from 0-7)

GetFolderFlags as Integer
method, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Get the folder flags for the folderitem to the given value. Returns a negative if there is an error.
Notes:
Returns the frFlags of a folder. If you pass in a non-existing folder, a negative error code is returned instead.
The frFlags are similar to the fdFlags (see GetFileFlags), but only a subset of them is used with folders.

GetIconFromTC(maxDepth as Integer, typeCode as String, creatorCode as String[,size as integer]) as Picture
method, Icon Service Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: returns allways nil
Function: Returns a picture with the icon for the given Type and Creator combination.
Example: iconpicture=GetIconFromTC(32,"TEXT","ttxt") ' the SimpleText textfile icon
Notes: Optional you can specify size for 16 pixel wide icons instead of 32 pixel ones.

Icon as picture
method, Icon Service Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Returns an picture with the icon of a Folderitem.
Example: p=systemfolder.icon
Notes: The picture has white space around the Icon!

Icon(width as integer) as picture
method, Icon Service Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Returns an picture with the icon of a Folderitem for the given iconsize.
Example: p=systemfolder.icon(16)
Notes: The picture has white space around the Icon!

IsFileOpen as Boolean
method, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: returns allways false
Function: Returns true if the file is opened by some application.
Example: bool=f.IsFileOpen
Notes:
Returns true if the item is a file and that file is open (in use). Equivalent to calling GetFileAttribute and testing bit 7.
Most times RB won't let you change something if a file is open.

IsMovieFile as boolean
method, Folderitem Sa, 27. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Compiler, but untested.
Function: Checks whether quicktime can open this file as a movie.
Example:
if f.ismoviefile then
'use as movie
else
msgbox f.name+" is not a movie file."
end if
Notes:
Take care that Text files will be valid for movies because quicktime allows use of textfiles for undertitles in movies.
So on Mac you should check for filetype "TEXT", too.

IsOnRemoteVolume as Boolean
method, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: returns allways false
Function: Returns true if the file is on a remote volume.
Example: bool=f.IsOnRemoteVolume

IsPictureFile as boolean
method, Folderitem Sa, 27. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Compiler, but untested.
Function: Checks whether quicktime can open this file as a picture.
Example:
if f.ispicturefile then
'use as picture file
else
msgbox f.name+" is not a picture file."
end if
Notes: Some user reported that PDF files are seen as valid pictures, too.

IsResourceForkOpen as Boolean
method, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: returns allways false
Function: Returns true if the file's resourcefork is open.
Example: bool=f.IsResourceForkOpen
Notes:
Returns true if the item is a file and that its resource fork is open (in use). Equivalent to calling GetFileAttribute and testing bit 2.

One of the functions is particularly helpful: RB 1.1.1 (and before) crashes when you open and then again close the resource fork of a file that is already opened by another application or by the RB IDE. To prevent that, you can use IsResourceForkOpen before you open the resource fork and then do not close the resource fork again if it was open before.

Kind as string
method, Folderitem Fr, 31. Mai 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Returns a string about the kind of the document.
Example: s=file.kind
Notes: e.g. for a Realbasic document on Mac OS X "REALbasic Document" or on Mac OS 9 something like "REALbasic 4.0.2fc6 Mac OS X Document".

Launch(inFront as Boolean)
method, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Compiled, but not tested.
Function: Launches a file.
Example: document.Launch true
Notes: In Realbasic 4.5 Realsoftware introduces a new Launch variant: "Launch(inFront)". To be compatible I renamed the old Launch method to MBSLaunch and added a Launch method which is compatible to Realbasic's.

LogicalFileDataLength as double
method, File Size Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Returns the length of the logical disk space used for this file's data fork.
Example: filesize.text=format(file.LogicalFileDataLength,"0")
Notes:
This function works for files bigger than 2 GB which RB's built in functions don't.
On Windows the physical size reported is equal to the logical size, because there is no function for the physical size.

LogicalFileResLength as double
method, File Size Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> 0.
Function: Returns the length of the logical disk space used for this file's resourcefork.
Example: filesize.text=format(file.LogicalFileResLength,"0")
Notes:
This function works for files bigger than 2 GB which RB's built in functions don't.
On Windows the physical size reported is equal to the logical size, because there is no function for the physical size.

LogicalFileTotalLength as double
method, File Size Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Returns the length of the logical disk space used for this file's datafork.
Example: filesize.text=format(file.LogicalFileTotalLength,"0")
Notes:
This function works for files bigger than 2 GB which RB's built in functions don't.
On Windows the physical size reported is equal to the logical size, because there is no function for the physical size.

LongPath as string
method, Folderitem Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Returns the long path for the file.
Example: msgbox f.longpath
Notes:
Should be the same as f.absolutepath
Works with Windows NT 4 or newer.

MBSLaunch(inFront as Boolean) as Boolean
method, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Compiled, but not tested.
Function: Launches a file.
Example: b=document.MBSLaunch(true)
Notes:
In Realbasic 4.5 Realsoftware introduces a new Launch variant: "Launch(inFront)". To be compatible I renamed the old Launch method to MBSLaunch and added a Launch method which is compatible to Realbasic's.

The return value is true if no immediate error occured. It would be false, for instance, if the FolderItem object does not exists, is a folder, or is not allowed to be opened (can happen with files on network volumes, as well as in Mac OS X environments).

OpenAsCMProfile as CMProfile
method, ICM Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Opens a profile file.
Notes:
This function uses pathes and may fail because of duplicate disk names!
On a Mac you should be able to use the Colorsync stuff to find the profiles on disk.

OpenAsColorSyncProfile as ColorSyncProfile
method, ColorSync Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> nil
Function: Opens the file as a ColorSync profile.

OpenAsJPEG([[allowdamaged as Boolean],fileposition as integer]) as picture
method, Storing pictures Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Reads a picture from a JPEG file.
Example:
dim f as folderitem
f=desktopfolder("a great jpeg picture.jpg")
me.backdrop=f.openasjpeg
Notes:
This methods should read all JPEG files you can get, but I've only tested it for 32 bit color and 8 bit grayscale.

This method is not depending on any library! It works without QuickTime even on System 7, but as it contains everything needed this method is around 120 KB big!
(REALbasic's OpenAsPicture depends on QuickTime)

I wrote it mainly because Realbasic's built in OpenAsJPEG code crashes badly if your picture is not full downloaded. For example if you have a webbrowser you can now show JPEGs while you download them. Normally you can see a good picture allready with 50% of the data.

REALbasic's OpenAsPicture in contrast crashes if the picture is not 100% downloaded or instead of a crash you get a white picture.

See the folder "jpeg load crashtest" in the examples.

The two parameters are both optional. The second is to give a file position to start reading. This way you can load several JPEGs from different file position from one file.

OpenAsLargeBinaryStream(forkName as String, write as Boolean) as LargeBinaryStream
method, Large binary stream Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Opens a file as a LargeBinaryStream.
Example: l=f.OpenAsLargeBinaryStream(SystemDataForkName,true)
Notes: Use SystemDataForkName or SystemResourceForkName for the fork names.

OpenAsPNG([fileposition as integer]) as picture
method, Storing pictures Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Reads a picture from a PNG file.
Example:
dim f as folderitem
f=desktopfolder("a great picture.png")
me.backdrop=f.openaspng
Notes:
This methods should read all PNG files you can get.

This method is not depending on any library! It works without QuickTime even on System 7, but as it contains everything needed this method is around 130 KB big!
(REALbasic's OpenAsPicture depends on QuickTime)

The optinal parameter is to give a file position to start reading. This way you can load several PNGs from different file position from one file.

OpenAsResStream(write as Boolean) as ResStream
method, Ressourcefork Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> nil.
Function: Opens a file's resourcefork as a resstream.

OpenAsTiff() as picture
method, Storing pictures Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Reads a picture from a TIFF file.
Example:
dim f as folderitem
f=desktopfolder("a great picture.tiff")
me.backdrop=f.openastiff
Notes:
This method is not complete. It reads some TIFFs, but not all.

This method is not depending on any library! It works without QuickTime even on System 7, but as it contains everything needed this method is around 270 KB big!
(REALbasic's OpenAsPicture depends on QuickTime)

OpenWithApp(app as FolderItem, inFront as Boolean) as Boolean
method, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Compiled, but not tested.
Function: Opens a file using the given application.
Example: b=document.OpenWithApp(Simpletext,true)
Notes: Similar to Launch (see Folderitem.Launch), with the additional option to specify the application that should be used to open the FolderItem object. Passing nil in the app parameter is functionally identical to calling Launch.

Permissions as Permissions
method, Folderitem Fr, 17. Mai 2002
Mac OS Classic: -> nil. Mac OS Carbon: Works. Windows: -> nil.
Function: Returns an object for the Permissions of a file.

PhysicalFileDataLength as double
method, File Size Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Returns the length of the physical disk space used for this file's data fork.
Example: filesize.text=format(file.PhysicalFileDataLength,"0")
Notes:
This function works for files bigger than 2 GB which RB's built in functions don't.
On Windows the physical size reported is equal to the logical size, because there is no function for the physical size.

PhysicalFileResLength as double
method, File Size Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> 0.
Function: Returns the length of the physical disk space used for this file's resourcefork.
Example: filesize.text=format(file.PhysicalFileResLength,"0")
Notes:
This function works for files bigger than 2 GB which RB's built in functions don't.
On Windows the physical size reported is equal to the logical size, because there is no function for the physical size.

PhysicalFileTotalLength as double
method, File Size Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Returns the length of the physical disk space used for this file.
Example: filesize.text=format(file.PhysicalFileTotalLength,"0")
Notes:
This function works for files bigger than 2 GB which RB's built in functions don't.
On Windows the physical size reported is equal to the logical size, because there is no function for the physical size.

SaveAsJPEG(quality as integer[,fileposition as integer]) as boolean
method, Storing pictures Mi, 31. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Saves a picture into a file using JPEG compression.
Example:
dim f as folderitem
f=desktopfolder("a great jpeg picture.jpg")
if f.saveasjpeg(75) then
msgbox "Picture saved."
end if
Notes:
This methods saves 32bit pictures to a file using JPEG Compression. Using the parameter you can specify the quality in range between 25 and 100%

This method is not depending on any library! It works without QuickTime even on System 7, but as it contains everything needed this method is around 100 KB big!
(REALbasic's SaveAsJPEG depends on QuickTime)

See the "SaveJPEG without QuickTime" example.

You may use the function picture.bitmap to make sure that the picture is a bitmap, because this function works only for bitmap pictures.

Improved for RB 4.5 on Windows to work better by not flipping the image randomly.

The second parameter is optional. There you can give a file position where to start writing. This way you can save several JPEGs to different file position inside one file.

SetFileFlags(flags as Integer) as Integer
method, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Set the file flags for the folderitem to the given value. Returns 0 if okay.
Example:
For example, clearing a file's hasCustomIcon flag works like this:
fdFlags = f.GetFileFlags
if fdFlags >= 0 then
err = f.SetFileFlags(BitSet(fdFlags, 10, false))
if err <> 0 then
... oops, an error occured
(for instance, the disk could be write protected)
end
end
Notes:
Sets the fdFlags of a file. Returns an error code (or zero if no error occured). Possible error conditions include "disk is write protected" and "file not found".
When changing flags of a file, use GetFileFlags to get the original flags, then clear or set the flags by using BitwiseAnd and BitwiseOr and call SetFileFlags to set the new flags.

SetFolderFlags(flags as Integer) as Integer
method, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Set the folder flags for the folderitem to the given value. Returns 0 if okay.
Notes:
Sets the frFlags of a folder. Returns an error code (or zero if no error occured). Possible error conditions include "disk is write protected" and "folder not found".
When changing flags of a folder, use GetFolderFlags to get the original flags, then clear or set the flags by using BitwiseAnd and BitwiseOr and call SetFolderFlags to set the new flags.

ShortPath as string
method, Folderitem Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Returns the short path for the file.
Example: msgbox f.ShortPath
Notes:
In contrast to long path this is the short 8.3 path for Windows.
You need this for the WindowsMCI object.
Works with Windows NT 4 or newer.

Unixpath() as string
method, Folderitem So, 28. Apr 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Returns the native path for the file.
Example: msgbox f.unixpath
Notes:
test on the Desktop could be this:
On Mac OS X: /Users/cs/Desktop/test
On Mac OS 9: Mac OS 9:Desktop folder:test
On Windows: c:\windows\desktop\test

This function will return an empty string if the path can not be encoded in a Realbasic String. For my tests ICQ's path which is includes the folder name "ICQ 3.0 ƒ" can not be converted to MacRoman for some reason.

UnMount as Boolean
method, Folderitem Fr, 30. Aug 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Unmounts a volume.
Example:
if disk.unmountVolume then
msgBox "Volume unmounted."
else
msgBox "There was an error!"
end if
Notes:
On Windows is no unmounting.
This works on Mac OS X for my internal disks, the Firewire disk, the iPod and my DVD drive.
Don't try it with the start volume! The Finder will complain!

VolGetFolderItemID(createFileIDs as Boolean) as Integer
method, Volume Information Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Returns the unique FileID or DirID of a FolderItem.
Notes:
Returns the unique FileID or DirID of a FolderItem. This ID is unique over all items on the same volume. The value 2 always identifies the root directory, all negative values and positive ones above 15 are used for user-created files and folders, while the values 3-15 are used internally by the File System (for the Desktop Database, for example).
If the item does not exists, 0 (zero) is returned instead.

IDs for Folders can always be resolved back to a FolderItem using VolResolveID, while resolving FileIDs only works when they've previously been created explicitly. To create a resolvable FileID, pass true to the createFileIDs parameter. But be aware that if the FileID can not be created (because the disk is locked or because the File System Format does not support it), the call will fail and a zero will be returned!

So, if you are just interested in reading the FileID, pass false to the second parameter. This will not fail even there hasn't been created a resolvable ID for that file yet.

VolSupportsCatSearch as Boolean
method, Catalog Search Di, 23. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: returns allways false
Function: Returns true if this volume supports Catalog Search which only HFS(+) volumes does for now.
Example:
if v.VolSupportsCatSearch then
msgbox "Catsearch class will be fast!"
end if
Notes: Returns true if the volume is valid and supports the CatSearch functions. Returns false otherwise. From this you can tell whether a search will be fast or slow when using CatSearchOpen with the "allowRecursiveSearch" parameter set to true.

VolumeFree as Double
method, Volume Information Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Returns the size of the free space of the volume which the folderitem objects points to.
Example:
1. a short:
msgBox "The volume with your system folder has "+str(systemfolder.volumeSize)+" Bytes free."
2. a nicer:
dim d as double
dim s as string

d=systemfolder.VolumeFree

if d>10000.0 then
if d>10000000.0 then
if d>10000000000.0 then
s=format(d/1024.0/1024.0/1024.0,"0")+" GigaBytes"
else
s=format(d/1024.0/1024.0,"0")+" MegaBytes"
end if
else
s=format(d/1024.0/1024.0,"0")+" KiloBytes"
end if
else
s=format(d,"0")+" Bytes"
end if

msgBox "On your drive with the system folder you have "+s+" free."
Notes: This should be used to handle any volume size.

VolumeFreeKB as Integer
method, Volume Information Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Returns the size on the free space on volume which the folderitem objects points to.
Example: msgBox "The volume with your system folder has "+str(systemfolder.volumeSizeKB)+" KBytes free."
Notes: This can't work with anything bigger than 2048 Gigabytes.

VolumeInformation as VolumeInformation
method, Volume Information Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: -> nil.
Function: Returns a VolumeInformation object with detailed information about the volume where the folderitem's file is located on.
Notes: May return nil on errors.

VolumeSize as Double
method, Volume Information Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Returns the size on the volume which the folderitem objects points to.
Example:
1. a short:
msgBox "The volume with your system folder is "+str(systemfolder.volumeSize)+" big."
2. a nicer:
dim d as double
dim s as string

d=systemfolder.volumesize

if d>10000.0 then
if d>10000000.0 then
if d>10000000000.0 then
s=format(d/1024.0/1024.0/1024.0,"0")+" GigaBytes"
else
s=format(d/1024.0/1024.0,"0")+" MegaBytes"
end if
else
s=format(d/1024.0/1024.0,"0")+" KiloBytes"
end if
else
s=format(d,"0")+" Bytes"
end if

msgBox "Your drive with the system folder is "+s+" big."
Notes: This should be used to handle any volume size.

VolumeSizeKB as Integer
method, Volume Information Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Returns the Size on the volume which the folderitem objects points to.
Example: msgBox "The volume with your system folder is "+str(systemfolder.volumeSizeKB)+" KB big."
Notes: This can't work with anything bigger than 2048 Gigabytes.

VolumeSupportsLargeFiles() as Boolean
method, Large binary stream Sa, 27. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: returns allways false;
Function: Checks whether a Volume supports the saving of files larger than 2 Gigabytes.
Example:
if f.VolumeSupportsLargeFiles then
' you can save more than 2 GB files on f if enough space is free
end if
Notes: Not yet implemented for Windows.

RemoveLoginItem(appfile as folderitem, allusers as boolean)
global method, Login Items Sa, 27. Jul 2002
Mac OS Classic: Does nothing Mac OS Carbon: Works Windows: Does nothing
Function: Removes a file to the loginitems list.
Example:
dim f as folderItem

f=app.applicationFile
if RemoveLoginItem(f,false) then
msgBox f.displayName+" has been added to the login items!"
else
msgBox "Something went wrong."
end if
Notes:
The items are compared by path.
Returns true if item was found and the new list is written correctly to disk.
allusers decides whether to set it for all user or the current one.

Contact

Written 2002 by Christian Schmitz. Feel free to ask or report mistakes to realbasic@macsw.de.
Thanks.

This resource fork intentionally left blank ˇˇ